home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 038a / ezwindo1.zip / EZWINDO.DOC < prev    next >
Text File  |  1991-01-19  |  13KB  |  288 lines
  1.                   The EZ-WINDOWS PullDown Menu System
  2.  
  3.       "Terrific, a beautiful piece of programming!" - Duiven, Holland
  4.  
  5.  
  6.            A Complete Menu System for the QuickBasic 4.x Compiler
  7.             and MS Professional Development System 7.0 and up.
  8.  
  9.                                   by
  10.  
  11.             StrongSoft Engineering
  12.                           3155 S.W. 178th Ave
  13.                             Aloha, OR 97006
  14.  
  15.        Documentation written & prepared by John C. Strong
  16.  
  17.  
  18. OVERVIEW
  19.  
  20.      This routine is intended to allow a programmer to present the user
  21. with options in an organized and aesthetic way.  The PullDown Menu System was
  22. indeed modeled after the very pulldown menu used in the QuickBASIC 4.x
  23. environment.  
  24.  
  25.      I wrote this routine out of frustration, actually.  I didn't want to
  26. take the time to write a pulldown menu routine, yet none of the commercially
  27. available libraries offered the options that I needed.  So I just sat down
  28. one day and wrote it, and here it is.
  29.  
  30.      The PullDown Menu System is very easy to integrate in a QB program,
  31. yet offers all the options someone might expect in a commercial software
  32. package.  To use this routine in a program, all that is required is a few
  33. arrays containing formatting information for the pulldown menu and an array
  34. containing the actual text used.  Then a simple CALL statement will take care
  35. of the rest!  Don't worry -- loading the arrays required for the routine is
  36. very straightforward and uncomplicated, and the results are definitely worth
  37. it!
  38.  
  39.      The advantages of using this routine are both numerous and obvious, but
  40. there is one disadvantage:  the code size is rather large.  But the programs
  41. that need such a pulldown menu routine are the ones that need to present a
  42. multitude of options to the user -- such a program will naturally be large
  43. anyway, so the relative code size of the PullDown Menu System shouldn't make
  44. a big difference.
  45.  
  46.  
  47. REQUIREMENTS
  48.  
  49.      The PullDown Menu System requires QuickBASIC 4.0 Compiler or above.  I
  50. don't know if it will work with earlier versions.  I believe earlier versions
  51. of QuickBASIC modify the stack a bit differently when passing parameters to
  52. assembler routines, which would definitely cause problems.  So if you don't
  53. have version 4.0 or later, you would be doing yourself a great favor by
  54. upgrading if for no other reason than to enjoy the benefits of a superior
  55. programming environment provided by QB45 or PDS 7.0.
  56.  
  57.      You can use this routine inside the QB environment or in a compiled
  58. .EXE file.  Two Quick Libraries are provided for program development inside
  59. QB and two libraries are provided for compiled programs.    
  60.  
  61.  
  62. USING THE PULLDOWN MENU SYSTEM
  63.  
  64.     Using this routine requires the dimensioning and loading of several
  65. arrays and the actual call to the routine.  When calling the routine, several
  66. conventions must be observed:
  67.  
  68.      1)    All non-string variable arguments must be the integer type,
  69.            denoted by the percent sign %, i.e., ITEMSLCT%.  Alternativ-
  70.            ely, the DEFINT statement can be used at the beginning of
  71.            your program which will take care of this automatically.  You
  72.            can also pass literals instead of integer variables, but only
  73.            for arguments that are not modified by the routine.  The best
  74.            thing to do is just pass variables, which requires less stack
  75.            space than literals.
  76.  
  77.      2)    The arguments passed must be in proper order or the routine
  78.            will not work, possibly locking up your system.
  79.  
  80.      3)    All arguments must be present or the routine will not work,
  81.            possibly locking up your system.
  82.  
  83.  
  84.  
  85. CALLING THE ROUTINE
  86.  
  87.      This is the required format for calling this routine:
  88.  
  89.  
  90.      CALL PULLDOWN(MENUBAR$,MenuRow%,MenuCol%,MenuFG%, MenuBG%,HiliteFG%,
  91.                    HiBarFG%,HiBarBG%,NonValidFG%,HiPos1%(),HiPos2%(),
  92.                    MaxSize%(),MaxItems%(),item$(),valid%(),toggle%(),ms%,
  93.                    ClearAfter%,Seed%,SoundOn%,Blink%,MenuSlct%,ItemSlct%)
  94.  
  95.  
  96.      Arguments:     MENUBAR$ - A string variable holding each pulldown menu
  97.                                name.  The number of menus is determined by
  98.                                the number of names is this string, which
  99.                                must be separated by at least one space on
  100.                                each side.  A space character must be the last
  101.                                character in the string.
  102.  
  103.                     MenuRow% - The row on which the menu bar will be 
  104.                                displayed.
  105.  
  106.                     MenuCol% - The column of the leftmost character in the
  107.                                menu bar.  For a full length menu bar, this
  108.                                would be set to one (1).
  109.  
  110.                      MenuFG% - The foreground color of the menubar and menus.
  111.  
  112.                      MenuBG% - The background color of the menubar and menus.
  113.  
  114.                    HiLiteFG% - The foreground color of the 'hot' letter in
  115.                                each selection.  Bright white (15) or yellow
  116.                                (14) work the best.
  117.  
  118.                     HiBarFG% - The foreground color of the text selected by
  119.                                the hilite bar.
  120.  
  121.                     HiBarBG% - The background color of the hilite bar.
  122.  
  123.                  NonValidFG% - The foreground color of the selections not 
  124.                                currently valid.  Gray (8) works the best here.
  125.  
  126.                    HiPos1%() - The integer array, dimensioned to the number of
  127.                                menus, holding the position of the 'hot'
  128.                                letter in each menu name in the MENUBAR$
  129.                                variable.  These letters will be hilited with
  130.                                the color specified in the HiliteFG% variable.
  131.  
  132.                    HiPos2%() - A 2-dimensional integer array holding the 
  133.                                position of the 'hot' letter in each menu item
  134.                                for each menu. It's first dimension is the
  135.                                number of the menu, the second is the 
  136.                                number of the selection in the menu.  
  137.                                Dimension it for the number of menus and the 
  138.                                number of items in the largest menu.  For
  139.                                example,
  140.                                     DIM HiPos2%(menu%,slct%)
  141.  
  142.                   MaxSize%() - An integer array holding the length of the
  143.                                longest item in each menu.
  144.  
  145.                  MaxItems%() - An integer array holding the number of items in
  146.                                each menu.
  147.  
  148.                      Item$() - A 2-dimensional array holding the items for
  149.                                selection for each menu.  It is dimensioned
  150.                                like HiPos2%(),
  151.                                     DIM Item$(menu%,slct%)
  152.  
  153.                     Valid%() - A 2-dimensional flag array that determines if
  154.                                an item is valid for selection or not.  A value
  155.                                of 1 is valid; 0 means not valid, and the item
  156.                                is grayed-out.  It is dimensioned like
  157.                                HiPos2%().
  158.  
  159.                    Toggle%() - A 2-dimension flag array that determines the 
  160.                                toggling status of each item in each menu.  
  161.                                
  162.                                    2   -   exclusive toggle, on
  163.                                    1   -   inclusive toggle, on
  164.                                    0   -   no toggling
  165.                                   -1   -   inclusive toggle, off
  166.                                   -2   -   exclusive toggle, off
  167.  
  168.                                If toggling is used in a menu, it must all be
  169.                                of one type, either all exclusive or all
  170.                                inclusive.  Otherwise, it won't work properly.
  171.                                Toggle%() is dimensioned like HiPos2%().
  172.  
  173.                          ms% - Flag to indicate mouse support.  If ms%=0, the
  174.                                routine ignores the mouse if one is present.
  175.                                ms%=1 tells the routine to use the mouse.
  176.  
  177.                  ClearAfter% - If ClearAfter%=1, the menu will be erased after
  178.                                a selection is made.  A value of zero will 
  179.                                inhibit the erasing of the menu.
  180.  
  181.                        Seed% - When PULLDOWN is first called, the menu name
  182.                                corresponding to the number in this variable 
  183.                                is hilited for selection.
  184.  
  185.                     SoundOn% - If set to zero (0), the routine will not make
  186.                                any sound.
  187.  
  188.               Blink% - If set to one (1), the selected item will blink
  189.                    2 times after selection.
  190.  
  191.      Returned:     MenuSlct% - The number of the menu containing the item that
  192.                                was selected.
  193.  
  194.                    ItemSlct% - The number of the item selected.
  195.                               
  196.                                                             
  197.     In addition, you can tell PULLDOWN to put in a dividing line with a 
  198. simple command.  All you do is insert a certain control code into your
  199. ITEM$() array.  For example, to put a dividing line 10 characters long in
  200. your first menu after the third item, your program should define ITEM$(1,4) as:
  201.  
  202.             ITEM$(1,4) = "~10"
  203.  
  204. The tilde "~" tells PULLDOWN to create a dividing line, its length determined
  205. by the two characters directly following the tilde.
  206.  
  207.      The source code for PDDEMO is well documented and will provide a little
  208. more clarity on the function of each of these variable.  I encourage you to
  209. play around will PDDEMO a bit - get a feel for it by modifying it and seeing
  210. what it does.  Be sure to observe the calling conventions, though.
  211.  
  212.  
  213. COMPILING
  214.  
  215.     To create an .EXE file, follow these steps:
  216.  
  217.           1)   During development, use the EZQB.QLB (or EZPDS.QLB) Quick
  218.            Library inside the QB environment.
  219.  
  220.           2)   When you're ready to compile the finished program, first
  221.                decide if you want a stand-alone program or one that needs the
  222.                BRUNxx.exe file to run.  Then go to the DOS prompt in your QB
  223.                directory and use this syntax to compile your program:
  224.  
  225.                     BC PROGRAMNAME [/O],,nul       
  226.  
  227.                where PROGRAMNAME is the name of your basic program (no
  228.                extension), and the [/O] option tells QB to compile a stand-
  229.                alone program.  You may leave this option off if you want,
  230.                which will result in an executable file that needs the
  231.                BRUNxx.EXE file.  For example, to compile PDDEMO.BAS for
  232.                stand-alone program, type
  233.  
  234.                     BC PDDEMO /O
  235.  
  236.           3)   Now is when you link in the EZQB.LIB (or EZPDS.LIB) library
  237.                to the object code produced by the compiler.  From the DOS
  238.                prompt use this syntax to link your program:
  239.  
  240.                     LINK [/E] PROGRAMNAME,,,EZQB
  241.  
  242.                The [/E] is the EXEPACK option which produces a
  243.                smaller executable file and should be used for most every 
  244.                program that you may write.
  245.  
  246.           4)   You should now have an executable version of your QB program
  247.                in the QBxx directory.  Remember, if you didn't use the [/O]
  248.                option, the BRUNxx.EXE must be present.
  249.  
  250.  
  251.  
  252. HELP A BUDDING ENGINEER!
  253.  
  254.      If you think this pulldown menu routine will be useful to you, I would
  255. greatly appreciate a little donation to get me through the last year of 
  256. engineering school.  A $5.00 registration fee is all that's needed to get on 
  257. the mailing list and receive updates to PULLDOWN plus customer support.
  258.  
  259.  
  260. MORE ROUTINES!!
  261.  
  262.      If you run the EZDEMO1.EXE program on your disk, you will see a collection
  263. of my favorite routines that I would like to make available to you.  This is
  264. Volume 1 of the EZ-WINDOWS library.  I use these routines extensively in my
  265. programs, which not only saves a lot of time but also results in a professional
  266. looking program.
  267.  
  268.      Here is what you get:  1) the complete library of routines with full
  269. documentation;  2)  free updates when they become available;  3)  customer
  270. support.  Included in customer support is the "wish list".  If you have an
  271. idea for a routine, and I get enough suggestions from others for the same type
  272. of routine, I will write it up and send it out with the next update.  In 
  273. addition, I will be periodically updating my personal library with new
  274. routines which will be included in the next volume.  Each new volume can be
  275. obtained by registered users at a discount.
  276.  
  277.      I know a lot of you will want my source code, and I can understand that.
  278. I'm a little reluctant to give it out, but I will release it with the library
  279. for an extra fee.
  280.  
  281.      For ordering info, see the REGISTER.DOC file.
  282.  
  283.  
  284. AND LASTLY...
  285.  
  286.      Have a ball! 
  287.  
  288.